7.4.1 PivCardRequest/Parameters

Contains the settings for the import. See section 5, Advanced settings.

7.4.2 PivCardRequest/Agency

The Agency element contains information about the applicant's agency, and contains the block for the applicant.

Note: An agency group created through the Lifecycle API does not inherit any default roles from its parent group, and you cannot set default roles through the Lifecycle API. This means that for any new users created within this new group, you must specify all of the roles that you want to assign; if you do not specify any roles, the user receives the default Cardholder and Password User roles.

7.4.3 PivCardRequest/Agency/DeptCode

Internal name: Xg16

Encoded in the PrintedInfo block.

Mandatory only for Add; also mandatory for update if the agency is specified.

7.4.4 PivCardRequest/Agency/AgencyCode

Internal name: Xg1

Four alphanumeric characters. Encoded in the FASCN and in the PrintedInfo block.

Mandatory only for Add; also mandatory for update if the agency is specified.

7.4.5 PivCardRequest/Agency/FacilityCode

Internal name: Xg2

Encoded in the FASCN and in the PrintedInfo block.

Mandatory only for Add; also mandatory for update if the agency is specified.

7.4.6 PivCardRequest/Agency/AgencyName

Internal name: Name and Xu3

Used to identify the Agency. Also encoded in the DN for member Applicants.

Mandatory for Add; also mandatory for update if the agency is specified.

Note: Agency names must be unique. The import will fail if the agency name is not unique; this occurs even if a unique parent name is specified.

7.4.7 PivCardRequest/Agency/FacilityName

Not currently used.

7.4.8 PivCardRequest/Agency/DUNS

Internal name: Xg5

Needed if the Organizational Category (below) is set to Commercial.

Mandatory only for Add; also mandatory for update if the agency is specified.

7.4.9 PivCardRequest/Agency/OC

Internal name: Xg3

Organizational Category. Encoded in the FASCN.

An integer – the values map to the following categories:

• 1 – Federal

• 2 – State

• 3 – Commercial

• 4 – Foreign

Mandatory only for Add; also mandatory for update if the agency is specified.

7.4.10 PivCardRequest/Agency/OI

Internal name: Xg4

Organizational Identifier. Encoded in the FASCN.

Mandatory only for Add; also mandatory for update if the agency is specified.

7.4.11 PivCardRequest/Agency/Department

Internal name: Xg17 and Xu54

Encoded in the DN for member Applicants.

7.4.12 PivCardRequest/Agency/BaseDN

Internal name: OrgUnit and Xg15

If present, this is used as the default DN for member Applicants. The CN field is appended to this value.

7.4.13 PivCardRequest/Agency/Parent

Internal name: Parent

The name of the agency beneath which the specified agency should be positioned. For new agencies, if you do not specify a parent agency, the new agency is placed under the root. If you are specifying an existing agency for the user, make sure you specify the correct parent agency, or omit the Parent node; otherwise, the agency will be moved under the new parent.

Note: Parent agency names must be unique. The import will fail if two different agencies have the same name as the specified parent name.

7.4.14 PivCardRequest/Agency/AgencyAddress

Used for delivery addresses. Contains the following elements:

7.4.15 PivCardRequest/Agency/AdditionalAgencyFields

Contains any extended (Xg) agency fields. See section 3.8.2, Additional group fields for details.

7.4.16 PivCardRequest/Agency/Applicant

The Applicant element contains information about the applicant.

You can import a single applicant in each XML document.

7.4.17 PivCardRequest/Agency/Applicant/Personal

Contains the personal details of the applicant.

Mandatory for Add.

7.4.18 PivCardRequest/Agency/Applicant/Personal/FirstName

Internal name: FirstName

Mandatory.

7.4.19 PivCardRequest/Agency/Applicant/Personal/LastName

Internal name: Surname

Mandatory.

7.4.20 PivCardRequest/Agency/Applicant/Personal/NickName

Internal name: Xu49

7.4.21 PivCardRequest/Agency/Applicant/Personal/MiddleName

Internal name: Initial

7.4.22 PivCardRequest/Agency/Applicant/Personal/Suffix

Internal name: XuPIV4

7.4.23 PivCardRequest/Agency/Applicant/Personal/Title

Internal name: Title

7.4.24 PivCardRequest/Agency/Applicant/Personal/Email

Internal name: Email

This address is used for email notifications.

7.4.25 PivCardRequest/Agency/Applicant/Personal/Fax

Internal name: PhoneExt

7.4.26 PivCardRequest/Agency/Applicant/Personal/Cell

Internal name: MobileNumber

7.4.27 PivCardRequest/Agency/Applicant/Personal/Phone

Internal name: PhoneNumber

7.4.28 PivCardRequest/Agency/Applicant/Personal/EmployeeID

Internal name: EmployeeID

This should be a unique identifier for the applicant.

Mandatory.

Appears within MyID Desktop as the Security field. For a PIV user (that is, a user who belongs to an agency that does not have a code of 9999) this value is used for the PI (Person Identifier) value in the FASC-N. Due to restrictions on the PI field in the FASC-N, this identifier must be a maximum of 10 numeric digits.

7.4.29 PivCardRequest/Agency/Applicant/Personal/Address

Used for delivery addresses. Contains the following elements:

• Address1

• Address2

• City

• StateZip

7.4.30 PivCardRequest/Agency/Applicant/Personal/BirthDate

Internal name: Xu37

Format: YYYY-MM-DD

7.4.31 PivCardRequest/Agency/Applicant/Personal/Nationality

Internal name: XuPIV1

A code referring to the nationality of the applicant. The possible values are:

7.4.32 PivCardRequest/Agency/Applicant/Personal/Citizenship

Reserved for future use. Do not use.

7.4.33 PivCardRequest/Agency/Applicant/Personal/CountryOfBirth

Internal name: XuPIV12.

Used for OPM Adjudication – contact customer support for more information, quoting reference SUP-123.

A two-character NCIC country code specifying the country of birth of the applicant. If the country is the United States of America, use the PlaceOfBirth node to specify the state.

7.4.34 PivCardRequest/Agency/Applicant/Personal/PlaceOfBirth

Reserved for future use.

7.4.35 PivCardRequest/Agency/Applicant/Personal/ExportRestrictions

Reserved for future use. Do not use.

7.4.36 PivCardRequest/Agency/Applicant/Authentication

Contains information about the security phrases for a user.

7.4.37 PivCardRequest/Agency/Applicant/Authentication/SecurityPhrase

Contains a pair of elements – a Prompt and an Answer – that provide a security phrase for the applicant.

You can have up to five SecurityPhrase elements, each containing a Prompt and Answer pair.

Note: If you provide any security phrases for an existing user, all existing security phrases on that user's account are removed and replaced with the newly-provided security phrases. You can use this feature to delete the security phrases from a user's account – provide a single Prompt with an empty Answer, and the user's security phrases will be removed. (If the minimum number of security phrases is set to 1, the user will still be prompted for a security phrase when attempting to log on, but will be unable to authenticate.)

7.4.38 PivCardRequest/Agency/Applicant/Authentication/SecurityPhrase/Prompt

Internal name: Question field in SecurityQuestions

Used to import a security question. If the question does not already exist, an entry is added to the SecurityQuestions table; this question will subsequently be available for use when setting security phrases in MyID.

The default security questions are:

7.4.39 PivCardRequest/Agency/Applicant/Authentication/SecurityPhrase/Answer

Internal name: SecurityPhrase field in UsersSecurityQuestions

Used to import an answer to a security question for an applicant. A hash of the answer is stored in the UsersSecurityQuestions table.

Important: Do not include any leading or trailing spaces in the security phrase answer. If you do include leading or trailing spaces, the user will be unable to authenticate to MyID.

Note: If you have set up the Security Phrase Complexity option within MyID to determine the complexity of security phrases, this is not enforced on any passwords that you import using the Lifecycle API.

You can encrypt the answer using a transport key – this allows you to maintain the security of the security phrase answer when you include it in the XML data.

To encrypt the answer:

1. Import your AES128 transport key into MyID using the Key Manager workflow.

2. External to MyID, encrypt the security phrase answer with the following settings:

   • Encode the security phrase answer as little-endian Unicode. Do not use a byte order mark.

     For example, a security phrase of answer would be encoded as:

     0061006E0073007700650072

   • Pad the data using ISO9797 Method 2 (pad with a single 0x80, then 0x00 until the block-length is reached).

   • Encrypt using CBC or ECB mode encryption.

3. Add the hex-encoded encrypted data to the Answer node.

4. Set the KeyName attribute of the Answer node to the name of the transport key you imported into MyID.

5. Set the Mode attribute of the Answer node to either CBC or ECB, depending on how you encrypted the answer.

For example:

• The transport key, MyTransportKey, has a value of:

  206890FC9B4EA1D0137D8C692B3BFCB6

• The security phrase is:

  answer

• In the import, use the following:

  <Answer KeyName="MyTransportKey" Mode="CBC">6713987B589F76BC4DA0F557D79A6275</Answer>

If you do not want to encrypt the answer in the XML document, omit the KeyName and Mode attributes. For example:

<Answer>plaintextanswer1234</Answer>

7.4.40 PivCardRequest/Agency/Applicant/Card

Used to specify details for the applicant's card.

7.4.41 PivCardRequest/Agency/Applicant/Card/CardProfile

If present, this will request a card of the given name for this applicant. If performing an update, or the card profile does not exist, no request will be made.

7.4.42 PivCardRequest/Agency/Applicant/Card/CardExpiryDate

Used to specify the expiry date for the card when it is issued. The card will expire on the date specified, or on the date the card profile specifies, whichever is earlier.

The format is YYYY-MM-DD – for example, 2016-12-25.

Note: If the Expire Cards at End of Day configuration option is set to Yes, the time portion of the card expiry date is set to 23:59 UTC – the end of the day. If the Expire Cards at End of Day option is set to No, the time portion is set to the time of the import. However, if the Expire Cards at End of Day option is set to No, and the card expiry date is constrained by an earlier card lifetime as configured in the credential profile, the time portion is set to 00:00 UTC – the start of the day.

Note: Some CAs do not allow control over the time portion of the certificate expiry. When MyID sets the lifetime of the certificate, the date is set as expected, but the time may not match exactly, depending on the certificate authority being used.

If you provide a date in the CardExpiryDate node, and this exceeds the Maximum Expiry Date set against the user account, the CardExpiryDate is ignored, and the Maximum Expiry Date is used in the request. This may be changed at the time of collection to an earlier date, if the lifetime configured in the credential profile limits it.

7.4.43 PivCardRequest/Agency/Applicant/Card/Renewal

Used to specify whether the card is a renewal of an existing card. If the user already exists, you must set this option to true or card request jobs will not be created.

Can be one of the following values:

• true – this is a card renewal.

• false – this is not a card renewal.

Note: For card renewals, you must specify the card's original serial number and device type using the PivCardRequest/Agency/Applicant/Card/Update node.

7.4.44 PivCardRequest/Group/User/Card/ImportCard

Used to specify whether to import a device (see section 3.11, Importing operator credentials).

Can be one of the following values:

• true – import a device.

• false – do not import a device.

7.4.45 PivCardRequest/Agency/Applicant/Card/CardRequestedBy

This is the logon name of the person requesting the card. Used for auditing purposes.

7.4.46 PivCardRequest/Agency/Applicant/Card/JobLabel

Allows you to specify a label for the renewal or replacement job. You can then search for this label in the Job Management or Batch Issue Card workflows.

7.4.47 PivCardRequest/Agency/Applicant/Card/Update

Used to specify the card being updated or renewed. You must make sure that the card is issued to the user.

7.4.48 PivCardRequest/Agency/Applicant/Card/Update/OriginalSerialNumber

The serial number of the card being updated or renewed. Used to target a specific card.

Mandatory if you have included the Update node.

7.4.49 PivCardRequest/Agency/Applicant/Card/Update/OriginalDeviceType

The device type of the card being updated or renewed.

Mandatory if you have included the Update node.

7.4.50 PivCardRequest/Agency/Applicant/Card/Update/StatusMapping

The status mapping code to be used when the card is updated.

See section 3.7.5, Status mapping codes for details.

7.4.51 PivCardRequest/Agency/Applicant/Card/Update/RevocationComment

A free text description that is stored in the database against certificates revoked by this update. Used in conjunction with the ReIssue option in ParametersXML.

7.4.52 PivCardRequest/Agency/Applicant/Card/Update/ParametersXML

Contains parameters for the card update job.

7.4.53 PivCardRequest/Agency/Applicant/Card/Update/ParametersXML/ReIssue

Set to 1 to request the reissuance of a device.

Reissuance is a type of card update job that, when collected, carries out the following:

• Revokes existing certificates present on the device.

• Re-applies data model electronic personalization.

• Issues and writes a new set of certificates onto the device (according to the credential profile).

• If the Rotate Keys On Card Update configuration option is set (on the Issuance Processes page of the Operation Settings workflow) applies the latest customer GlobalPlatform and PIV 9B keys.

7.4.54 PivCardRequest/Agency/Applicant/Card/Replacement

Allows you to provide the details of the credential being replaced.

7.4.55 PivCardRequest/Agency/Applicant/Card/Replacement/OriginalSerialNumber

The serial number of the card being replaced. Mandatory if you specify the Replacement node.

7.4.56 PivCardRequest/Agency/Applicant/Card/Replacement/OriginalDeviceType

The device type of the card being replaced. Mandatory if you specify the Replacement node.

Note: If you specify a valid serial number and device type for the card being replaced (that is, an existing credential that is currently assigned to the applicant) the original card is marked for cancellation and a new card request is created.

If the serial number is invalid (for example, the card does not exist, or is not assigned to any user) no card is marked for cancellation, but the replacement card is still requested.

If the serial number is valid but is assigned to another user, an error is generated; the card is not cancelled, and no replacement card is requested.

7.4.57 PivCardRequest/Agency/Applicant/Card/Replacement/StatusMapping

The status mapping ID for the replacement.

See section 3.7.5, Status mapping codes for details.

7.4.58 PivCardRequest/Agency/Applicant/Card/Reprovision

Set the value of this node to 1 to request a reprovision rather than an update.

A reprovision allows you to re-encode a card completely, based on the data in the MyID database, using the latest version of the credential profile used during issuance.

The card will have the same expiry date as the original card. New certificates may have longer expiration times than the original certificates, but these will not exceed the lifetime of the card itself. Certificates that were revoked externally to MyID will be replaced with new active certificates.

When requesting a reprovision, specify a status mapping with one of the following values:

• 83 – User details have changed.

• 84 – There is a problem with the device.

• 85 – New credential profile needs to be applied.

Note: If you specify any other status mapping, it is ignored – only these status mappings carry out reprovisions.

For example:

<Card>
  <CardProfile>Yubikey NoOTP</CardProfile>
  <CardRequestedBy>System</CardRequestedBy>
  <Update>
    <OriginalSerialNumber>8115516</OriginalSerialNumber>
    <OriginalDeviceType>YubiKey 4</OriginalDeviceType>
    <StatusMapping>84</StatusMapping>
  </Update>
  <Reprovision>1</Reprovision>
</Card>

7.4.59 PivCardRequest/Agency/Applicant/Card/CardLayout

Optionally, contains the name of the card layout to use when printing the requested card.

The card layout name must be valid for the card's credential profile at the point that the card is issued; if the card layout name is not valid, the request will not be processed.

7.4.60 PivCardRequest/Agency/Applicant/Card/SerialNumber

Used in conjunction with the PivCardRequest/Agency/Applicant/Card/DeviceType node to specify an exact card to be issued.

Note: If you have the Only Issue to Known Serial Numbers option set in the credential profile, and you specify a serial number for the card that has not previously been added to MyID, the import will fail. This failure will be included in the audit.

7.4.61 PivCardRequest/Agency/Applicant/Card/DeviceType

Used in conjunction with the PivCardRequest/Agency/Applicant/Card/SerialNumber node to specify an exact card to be issued.

7.4.62 PivCardRequest/Group/User/Card/Container

Used in conjunction with the CMSCardRequest/Group/User/Card/ImportCard node to specify the container that the authentication certificate is located in.

See section 3.11, Importing operator credentials.

7.4.63 PivCardRequest/Group/User/Card/Certificate

Used in conjunction with the CMSCardRequest/Group/User/Card/ImportCard node to specify the authentication certificate on the imported card. This must be the base64 representation of the certificate without headers, footers, or line breaks.

See section 3.11, Importing operator credentials.

7.4.64 PivCardRequest/Agency/Applicant/Account

Contains details of the applicant's account.

7.4.65 PivCardRequest/Agency/Applicant/Account/DN

Internal name: DistinguishedName

The DN of the users account in the LDAP

7.4.66 PivCardRequest/Agency/Applicant/Account/AlternateDN

Internal name: Xu55

If populated this is used in preference to the DN for cert requests

7.4.67 PivCardRequest/Agency/Applicant/Account/CN

Internal name: CommonName

7.4.68 PivCardRequest/Agency/Applicant/Account/OU

Internal name: OrganisationalUnit

7.4.69 PivCardRequest/Agency/Applicant/Account/UPN

Internal name: UserPrincipalName

7.4.70 PivCardRequest/Agency/Applicant/Account/SAMAccountName

Internal name: SAMAccountName

Optional SAMAccountName value for the user. Maximum of 20 characters.

7.4.71 PivCardRequest/Agency/Applicant/Account/Domain

Internal name: Domain

Optional Domain value for the user. Maximum of 50 characters.

7.4.72 PivCardRequest/Agency/Applicant/Account/LogonName

Internal name: LogonName

User’s name, used to log into MyID. Must be unique.

If no value is supplied, the PivCardRequest/Agency/Applicant/Personal/EmployeeID value is used instead.

7.4.73 PivCardRequest/Agency/Applicant/Account/Roles

Contains the details of the role you want to assign to the applicant.

Note: You can set any role for a user using the Lifecycle API – the roles you specify override any role restrictions. Also, the user will not receive any default roles that have been set up for their group; if you want to assign roles, you must include them explicitly. If you do not specify any roles, the user receives the default Cardholder and Password User roles.

7.4.74 PivCardRequest/Agency/Applicant/Account/Roles/Role

Contains details of the role you want to assign the applicant. Contains the following elements:

7.4.75 PivCardRequest/Agency/Applicant/Account/EntrustProfile

Specifies an Entrust profile template to use for the applicant. If specified, the applicant is added to Entrust using the template. See section 3.9, Importing users into Entrust for details.

7.4.76 PivCardRequest/Agency/Applicant/Account/MaxRequestExpiryDate

Allows you to set the maximum credential expiry date for a person – this allows you to specify the latest expiry date for any device issued to this person. Note that card requests cannot exceed the Lifetime set in the credential profile. Also, the credential profile can override the maximum expiry date for a person using the Ignore User Expiry Date option.

If the Expire Cards at End of Day configuration option is set to Yes, the time portion of the user's maximum credential expiry date is set to 23:59 UTC – the end of the day. If the Expire Cards at End of Day option is set to No, the time portion is set to 00:00 UTC – the start of the day.

Note: Some CAs do not allow control over the time portion of the certificate expiry. When MyID sets the lifetime of the certificate, the date is set as expected, but the time may not match exactly, depending on the certificate authority being used.

If you supply an expiry date in the CardExpiryDate node, it may also cause a check to be performed even when Max Request Expiry Date is not set in the same transaction using the Lifecycle API. See section 7.4.42, PivCardRequest/Agency/Applicant/Card/CardExpiryDate.

This setting affects all future device requests. It does not affect any issued devices or existing requests.

Note: This setting affects device requests made through the MyID Operator Client or the Lifecycle API. Requests made through MyID Desktop do not take this setting into account.

See the Requesting a device for a person section in the MyID Operator Client guide for more information.

7.4.77 PivCardRequest/Agency/Applicant/Account/UserSID

Allows you to provide the user security identifier (user SID) for a person.

For information on user SIDs, see the Including user security identifiers in certificates section in the Administration Guide.

7.4.78 PivCardRequest/Agency/Applicant/Position

Contains information about the applicant's position within the agency.

7.4.79 PivCardRequest/Agency/Applicant/Position/EmployeeAssociation

Internal name: Xu4 and Xu5

If "Contractor" this is appended to the Applicant's DN. The numeric version stored in Xu4.

Note: This node must be populated with a valid lookup value for new user imports.

The value can be one of the following:

• Employee

• Civil Worker

• Executive

• Uniformed

• Contractor

• Affiliate

• Beneficiary

7.4.80 PivCardRequest/Agency/Applicant/Position/EmployeeAffiliation

Internal name: Xu53

Used for graphical personalization of the card.

7.4.81 PivCardRequest/Agency/Applicant/Position/Rank

Internal name: Xu1

Used for graphical personalization of the card.

The value is restricted to a list of codes (for example, E-1 or O-6). See the schema for a full list.

7.4.82 PivCardRequest/Agency/Applicant/Position/EmergencyRole

Internal name: Xu8

Can be used to allow additional card profiles to Emergency Responders.

Can be one of the following values:

• Law Enforcement

• Paramedic

• Doctor

• Firefighter

• Bomb Disposal

• Biohazard

• None

7.4.83 PivCardRequest/Agency/Applicant/Position/Privilege

Internal name: Xu30

These details are visible in View Person and during card issuance approval.

7.4.84 PivCardRequest/Agency/Applicant/Position/ApplicantPosition

Internal name: Xu11

These details are visible in View Person and during card issuance approval.

7.4.85 PivCardRequest/Agency/Applicant/Position/ExtraInfo

Internal name: Xu10

A free-text field to leave comments about an applicant.

7.4.86 PivCardRequest/Agency/Applicant/Sponsor

Contains information about the applicant's sponsor. These details are visible in View Person and during card issuance approval.

7.4.87 PivCardRequest/Agency/Applicant/Sponsor/SponsorName

Internal name: Xu31

7.4.88 PivCardRequest/Agency/Applicant/Sponsor/SponsorPosition

Internal name: Xu32

7.4.89 PivCardRequest/Agency/Applicant/Sponsor/SponsorAgency

Internal name: Xu34

7.4.90 PivCardRequest/Agency/Applicant/Sponsor/SponsorEmail

Internal name: Xu36

7.4.91 PivCardRequest/Agency/Applicant/Sponsor/SponsorPhoneNumber

Internal name: Xu35

7.4.92 PivCardRequest/Agency/Applicant/Biometry

Contains information about the applicant's biometric details. Some of these details are printed on the reverse of some card layouts. Also included in adjudication requests.

7.4.93 PivCardRequest/Agency/Applicant/Biometry/HeightInches

Internal name: Xu14

The applicant's height in inches.

Note: This must be numeric. For example, 73 is accepted; 73" or 6'1" or 6 foot 1 inch are not allowed.

7.4.94 PivCardRequest/Agency/Applicant/Biometry/WeightLbs

Internal name: Xu15

The applicant's weight in pounds.

Note: The schema allows a total of eight characters for this value; however, this includes the space and lbs that is appended during the import. Accordingly there are four characters available for the numeric part of the weight; for example, 9999, which becomes 9999 lbs when it is imported into MyID. Do not include the lbs in the import data. 140 is accepted; 140 lbs or 10 stone are not allowed.

7.4.95 PivCardRequest/Agency/Applicant/Biometry/Gender

Internal name: Xu38

7.4.96 PivCardRequest/Agency/Applicant/Biometry/EyeColor

Internal name: Xu13

The value of this element is restricted. See the schema for details.

7.4.97 PivCardRequest/Agency/Applicant/Biometry/HairColor

Internal name: Xu12

The value of this element is restricted. The current list is:

7.4.98 PivCardRequest/Agency/Applicant/Biometry/Race

Internal name: Xu39

The value of this element is restricted. See the schema for details.

7.4.99 PivCardRequest/Agency/Applicant/Biometry/BioSample

Contains elements to contain fingerprints, EFT data and facial biometric scans.

The possible elements are:

• R_Little – the right little finger. Uses the data type BioFingerSample.

• R_Ring – the right ring finger. Uses the data type BioFingerSample.

• R_Middle – the right middle finger. Uses the data type BioFingerSample.

• R_Index – the right index finger. Uses the data type BioFingerSample.

• R_Thumb – the right thumb. Uses the data type BioFingerSample.

• L_Little – the left little finger. Uses the data type BioFingerSample.

• L_Ring – the left ring finger. Uses the data type BioFingerSample.

• L_Middle – the left middle finger. Uses the data type BioFingerSample.

• L_Index – the left index finger. Uses the data type BioFingerSample.

• L_Thumb – the left thumb. Uses the data type BioFingerSample.

• EFT – the applicant's EFT sample. Uses the data type EncodedData with an encoding type of bmp. As this is a standard format, the encoding type is actually ignored.

• FaceScan – the applicant's facial biometric sample. Uses the data type EncodedData with an encoding type of 385.

• IrisScan – the applicant's iris sample. Uses the data type EncodedData with an encoding type of 19794.

Important: If you include a biometrics node (for example, FaceScan) you must provide full and correct data for the biometrics. Do not leave the node empty – if you provide an empty node, the MyID client will not display the correct default image, but will display a broken image icon instead.

7.4.99.1 BioFingerSample

The BioFingerSample block is used to provide the data for a single fingerprint. It contains either:

• An EncodedData block (see below), with the Encoding type of 378 and a Data block of base64 data.

  Note: The RolledPrint element visible in the schema is no longer supported.

  or:

• A ReasonMissing element, which can be either Unprintable or Amputated, if you cannot provide the data for the specified finger.

For example (the Base 64-encoded binary data has been truncated):

<BioSample>
  <R_Index>
    <Encoding>378</Encoding>
    <Data>Rk1SACAy...</Data>
  </R_Index>
  <L_Index>
    <ReasonMissing>Unprintable</ReasonMissing>
  </L_Index>
...
</BioSample>

7.4.99.2 EncodedData

EncodedData blocks are used to include binary data in the imported XML; for example, fingerprint data, facial biometrics, and scanned documents. The EncodedData block has the following elements:

• Encoding – the type of data encoded in the block. This can be one of the following:

  • jpg – JPG image data.

  • gif – GIF image data.

  • png – PNG image data.

  • bmp – Windows bitmap image data.

  • 378 – INCITS 378 fingerprint data.

  • 385 – facial biometrics in ANSI/INCITS 385-2004 format.

  • 19794 – iris data.

• Data – a string of base64-encoded data containing the file to be uploaded.

• DateTaken – the date of the data; for example, when the photograph was taken, or when the fingerprints were captured.

  For user photos only, this is added to the XML within the ImageProps field in the People table in the MyID database.

  yyyy-mm-ddThh:mm:ss.nnn

  For example:

  2010-01-02T14:23:54.123

  Note: This is important for FIPS 201-2, as it lays down requirements for the maximum age of captured biometrics at the point of card issuance.

• Source – For user photos only, this is added to the XML within the ImageProps field in the People table. You can optionally use this field to store information about where the user photo came from.

7.4.99.3 Removing and updating fingerprints

You can update the fingerprints for applicants by supplying new fingerprint data. Updated fingerprint data for the specified fingers overwrites the previously-recorded fingerprints. If you are using different fingers (for example, if the applicant has had their right index finger amputated) you can remove the existing fingerprints for specific fingers by including an empty Data node.

For example:

<BioSample>
  <R_Index>
    <Encoding>378</Encoding>
    <Data/>
  </R_Index>
</BioSample>

Alternatively, you can use the ReasonMissing element to remove existing fingerprints:

<BioSample>
  <R_Index>
    <ReasonMissing>Amputated</ReasonMissing>
  </R_Index>
</BioSample>

All changes to the fingerprints stored for applicants are recorded in the audit trail.

7.4.100 PivCardRequest/Agency/Applicant/Biometry/Signature

Contains the applicant's digitized signature. Uses type EncodedData with an Encoding type of jpg. See section 7.4.99.2, EncodedData for details of the EncodedData format.

7.4.101 PivCardRequest/Agency/Applicant/IdentityDocs

Contains scans and information about the applicant's identity documents.

The following elements are included, one for each document:

• IdentityDoc1

• IdentityDoc2

• SPF10

Each document contains the following elements:

<NACI>
  <NACCaseNumber>65522</NACCaseNumber>
  <NACICaseNumber>65522</NACICaseNumber>
  <Check>
    <Type>SII</Type>
    <Status>AP</Status>
  </Check>
  <Check>
    <Type>DCII</Type>
    <Status>AP</Status>
  </Check>
  <Check>
    <Type>FBI CHF</Type>
    <Status>AP</Status>
  </Check>
  <Check>
    <Type>NACI</Type>
    <Status>WR</Status>
  </Check>
  <CardIssuanceApproved>YES</CardIssuanceApproved>
  <Comments></Comments>
</NACI>

7.4.103 PivCardRequest/Agency/Applicant/NACI/NACCaseNumber

Internal name: Xu40

7.4.104 PivCardRequest/Agency/Applicant/NACI/NACICaseNumber

Internal name: Xu46

7.4.105 PivCardRequest/Agency/Applicant/NACI/Check

Internal name: Xu41, Xu42, Xu43, Xu44, and Xu45

Contains one or more NACI background checks. You can have multiple Check elements in the import file. Each Check element contains the following elements:

• Type – The name of the background check. This can be one of the following:

  • SII

  • DCII

  • FBI Name – this option (which mapped to internal ID Xu43) is not supported. If you include this value in the import XML, it is ignored. If your system has been upgraded from an earlier version of MyID, your database may still have the Xu43 field; however, this field is no longer populated or used.

  • FBI CHF

  • NACI

• Status – the status of the NACI check. This can be one of the following:

  • NR – Not Requested

  • WR – Waiting Response

  • AS – Assessing Response

  • AP – Approved

  • RJ – Rejected

7.4.106 PivCardRequest/Agency/Applicant/NACI/CardIssuanceApproved

Internal name: UserDataApproved

Note: Throughout the PIV Integration Guide, this field is referred to as the User Data Approved flag.

Contains information on whether card issuance is approved for this applicant. Can be one of the following values:

• YES or 1

• NO or 0

This flag confirms that the data being sent to MyID has passed all the enrollment checks required for card issuance. You must set this flag when adding an applicant for the first time, and also on card renewal.

Note: The VettingDate defaults to the current date if CardIssuanceApproved is set to YES or 1, and an explicit VettingDate is not provided in the request.

7.4.107 PivCardRequest/Agency/Applicant/NACI/Comments

Internal name: Xu33

Free text description, up to 255 characters, of any background checks.

7.4.108 PivCardRequest/Agency/Applicant/NACI/VettingDate

Internal name: VettingDate

Contains the date on which the applicant's identity checks were carried out. The format is:

YYYY-MM-DDThh:mm:ss

You can use this field to ensure that the applicant's identity checks are renewed periodically. See the Identity checks section in the Administration Guide for details.

7.4.109 PivCardRequest/Agency/Applicant/Photo

Contains the applicant's photo. This is an EncodedData type block, with an Encoding value of jpg, gif, bmp or png, and the Data block containing a base64-encoded image.

See section 7.4.99.2, EncodedData for details of the EncodedData format.

7.4.110 PivCardRequest/Agency/Applicant/System

Contains system information for the application.

Required for PIV issuance.

7.4.111 PivCardRequest/Agency/Applicant/System/GUID

Internal name: Xu51

Unique ID used as part of the Card Holder Unique ID (CHUID).

Mandatory.

7.4.112 PivCardRequest/Agency/Applicant/System/CredNo

Internal name: Xu48

Credential Number – encoded in the FASC-N.

Mandatory.

7.4.113 PivCardRequest/Agency/Applicant/System/CS

Credential Series – always set to 1, but is ignored in the import anyway and the result is always 1. If you need to increment the credential series, contact customer support for details.

7.4.114 PivCardRequest/Agency/Applicant/System/POA

Legacy field – replaced by Applicant/EmployeeAssociation.

7.4.115 PivCardRequest/Agency/Applicant/System/ICI

Internal name: Xu47

The issue number of the next card to be issued. This is encoded in the FASCN. Recommend coding as a 1 always.

Mandatory only for Add.

7.4.116 PivCardRequest/Agency/Applicant/System/UserStatus

Internal name: Xu50

The state of the applicant in the process. This is displayed in the View Person workflow. Can be one of the following:

• Sponsored

• EnrollmentBegun

• EnrollmentComplete

• Vetting

• Escalated

• Approved

• CardRequested

• CardActivated

• Rejected

Note: The schema specifies a maximum of 50 characters, but the MyID limit is 40 characters.

7.4.117 PivCardRequest/Agency/Applicant/System/IssuanceNotifyURL

Internal name: Xu56

An override for the destination of the Card Issuance Notification XML that is sent when a card for the Applicant is issued.

Note: This notification is sent only when you issue a card through the MyID Desktop application. If you collect a card through the Self-Service App or Self-Service Kiosk, you must set up the Notifications table instead – see the PIV notifications section in the PIV Integration Guide for details.

7.4.118 PivCardRequest/Agency/Applicant/System/CancelNotifyURL

Specifies an URL to be used for notifications for card cancellations. This allows you to specify a different URL for cancellations and issuance.

7.4.119 PivCardRequest/Agency/Applicant/System/CMSIssuanceNotifyURL

Specifies an URL to be used for notifications for card issuance. This allows you to specify a different URL for cancellations and issuance.

Note: Reserved for future use.

7.4.120 PivCardRequest/Agency/Applicant/AdminGroups

An optional node that allows you to specify one or more administrative groups for the user. See the Administration Guide for details of setting up and using administrative groups.

The AdminGroups node contains one or more AdminGroup.

For example:

<AdminGroups>
  <AdminGroup>
    <Name>Group 1</Name>
  </AdminGroup>
</AdminGroups>

or:

<AdminGroups>
  <AdminGroup>
    <Name>Group 1</Name>
  </AdminGroup>
  <AdminGroup>
    <Name>Group 2</Name>
  </AdminGroup>
</AdminGroups>

If the user has existing administrative groups, they are replaced by the specified group or groups. If you specify an empty AdminGroups node, this clears all of the user's administrative groups. If you do not specify an AdminGroups node, the user's administrative groups remain unchanged.

7.4.121 PivCardRequest/Agency/Applicant/AdminGroups/AdminGroup

Specifies an administrative group for the user. You can have multiple AdminGroup nodes in the AdminGroups parent node. An AdminGroup node contains a single Name node.

7.4.122 PivCardRequest/Agency/Applicant/AdminGroups/AdminGroup/Name

Specifies the name of the administrative group for the user.

Note: The group must already exist in the MyID database. If the group does not exist, the import will fail.

7.4.123 PivCardRequest/Agency/Applicant/AdditionalFields

You can import information into additional extended fields using the data import. See section 3.8.1, Additional user fields for details.

7.4.124 PivCardRequest/Agency/Applicant/Actions

Contains actions to carry out for the applicant; for example, to remove or disable the user, or to cancel the user's credentials.

7.4.125 PivCardRequest/Agency/Applicant/Actions/ApplicantAction

Perform an action on the applicant. If you do not supply an action in the ApplicantAction element, a suspended applicant will be unsuspended.

The possible actions are:

• Disable – disable the user's account.

• Remove – remove the user from the system.

• CancelDevices – cancel all the user's credentials.

• CancelDevice – cancel specific credentials. Specify the credentials using the Device element.

• CancelJob – Cancel a specific job. Specify the job using the PivCardRequest/Agency/Applicant/Actions/Job element.

• CancelAllJobs – Cancel all jobs for the specified user.

• RenewCertificate – renew a certificate. Specify the certificate using PivCardRequest/Agency/Applicant/Actions/CertSerialNumber and PivCardRequest/Agency/Applicant/Actions/CertPolicyName.

7.4.126 PivCardRequest/Agency/Applicant/Actions/CertSerialNumber

Used in conjunction with an ApplicantAction of RenewCertificate and PivCardRequest/Agency/Applicant/Actions/CertPolicyName to specify a certificate to renew.

7.4.127 PivCardRequest/Agency/Applicant/Actions/CertPolicyName

Used in conjunction with an ApplicantAction of RenewCertificate and PivCardRequest/Agency/Applicant/Actions/CertSerialNumber to specify a certificate to renew.

7.4.128 PivCardRequest/Agency/Applicant/Actions/StatusMappingID

The action to apply to the user. This should be an ID that matches an entry in the StatusMappings table. It controls how certificates are revoked.

Note: You cannot specify negative IDs from the StatusMappings table – these are reserved for system use.

7.4.129 PivCardRequest/Agency/Applicant/Actions/RevocationComment

A free text description that is stored against revoked certificates in the database.

7.4.130 PivCardRequest/Agency/Applicant/Actions/Device

Specifies the credential (for example, a smart card) to cancel when you have selected CancelDevice for the ApplicantAction. Contains at least one DeviceIdentifier element. You can specify more than one credential to cancel by including multiple DeviceIdentifier elements.

7.4.131 PivCardRequest/Agency/Applicant/Actions/Device/DeviceIdentifier

Specifies the credential to be canceled or unlocked.

7.4.132 PivCardRequest/Agency/Applicant/Actions/Device/DeviceIdentifier/ SerialNumber

The serial number of the credential.

7.4.133 PivCardRequest/Agency/Applicant/Actions/Device/DeviceIdentifier/ SerialNumberField

The name of the field in which to look for the serial number. The field can be any field present in the vDevices view; for example, SerialNumber for the standard serial number or HIDSerialNumber for the HID serial number.

If you do not include a SerialNumberField node, MyID will use a default value of SerialNumber.

7.4.134 PivCardRequest/Agency/Applicant/Actions/Device/ProcessStatus

Used to specify the process status to be used for the credential being canceled.

You can use the following status codes, as listed in the DeviceProcessStatuses table in the database.

7.4.135 PivCardRequest/Agency/Applicant/Actions/Job

Contains a the ID of a job to cancel. Used in conjunction with an ApplicantAction of CancelJob.